Skip to main content

🖨️ CUPS — Printer Server on Raspberry Pi

This guide describes how to install and configure CUPS (Common Unix Printing System) on a Raspberry Pi, share printers over the network (Samba), install common drivers, and perform basic troubleshooting. Instructions aim for a simple home‑network setup — adjust security for production.

✅ Prerequisites​

  • Raspberry Pi with Raspberry Pi OS (or Debian) and network access
  • SSH or local terminal access with a sudo user
  • Printer with USB (or network-capable) connected to the Pi
  • Optional: USB webcam or other peripherals not required for printing

1) Update system​

Open a terminal and run:

sudo apt update
sudo apt upgrade -y
sudo apt autoremove -y

Reboot if kernel or core packages were updated:

sudo reboot

2) (Optional) Ensure locale is correct​

If you need English (UK) locale or want to fix locale warnings, enable and generate it:

sudo nano /etc/locale.gen
# uncomment: en_GB.UTF-8 UTF-8

sudo locale-gen en_GB.UTF-8
sudo update-locale LANG=en_GB.UTF-8
export LANGUAGE=en_GB.UTF-8
export LC_ALL=en_GB.UTF-8

# verify
locale

Adjust the locale values to your preferred locale if required.

3) Install CUPS​

Install the CUPS package:

sudo apt install -y cups

Enable and start the service:

sudo systemctl enable --now cups
sudo systemctl status cups --no-pager

4) Basic CUPS configuration (cupsd.conf)​

Edit the CUPS server config to allow local network access and restrict admin pages appropriately:

sudo nano /etc/cups/cupsd.conf

Recommended minimal changes for home network (example):

  • Listen on all interfaces (or bind to specific IP)
  • Allow local network access for printing and admin (replace with proper ACLs for production)

Example snippet to use inside cupsd.conf:

# Listen on all interfaces (optional)
Listen 0.0.0.0:631

# Restrict access to the server (printing/viewing)
<Location />
  Order allow,deny
  Allow @Local
</Location>

# Restrict access to the admin pages
<Location /admin>
  Order allow,deny
  Allow @Local
</Location>

# Restrict access to configuration files
<Location /admin/conf>
  AuthType Default
  Require user @SYSTEM
  Order allow,deny
  Allow @Local
</Location>

After edits restart CUPS:

sudo systemctl restart cups

Notes:

  • For production, use TLS and stricter ACLs. The above opens CUPS to the local network only.
  • If you run a firewall (ufw), allow port 631 (IPP): sudo ufw allow 631/tcp.

5) Add a local user to lpadmin​

Allow a user to manage printers via the web UI or lpadmin commands:

sudo usermod -aG lpadmin <username>
# example for default pi user:
sudo usermod -aG lpadmin pi

Log out and back in for group membership to take effect.

6) Share printers via Samba (optional)​

Install Samba and configure a simple shared printers section:

sudo apt install -y samba
sudo systemctl enable --now smbd

Edit Samba config:

sudo nano /etc/samba/smb.conf

Add or update a simple printers share (append to file):

[Printers]
   comment = All Printers
   path = /var/spool/samba
   browseable = no
   guest ok = yes
   read only = yes
   printable = yes

Create the spool directory and set permissions if needed:

sudo mkdir -p /var/spool/samba
sudo chown root:lp /var/spool/samba
sudo chmod 1775 /var/spool/samba
sudo systemctl restart smbd

Notes:

  • guest ok = yes is convenient for a trusted home network. For public or production use, require authentication and secure Samba properly.
  • If using Windows clients, install the printer from IPP (http://pi-ip:631) or via Samba.

Allow Samba ports in firewall if used:

sudo ufw allow Samba
# or individually:
sudo ufw allow 137/udp
sudo ufw allow 138/udp
sudo ufw allow 139/tcp
sudo ufw allow 445/tcp

7) Install common printer drivers​

Install recommended drivers for many laser and inkjet printers:

sudo apt install -y printer-driver-brlaser printer-driver-ippusbxd printer-driver-foo2zjs printer-driver-gutenprint

For Brother printers (network/backends) you may also install:

sudo apt install -y cups-backend-bjnp

After installing drivers, restart CUPS:

sudo systemctl restart cups

8) Add and manage printers​

Open the CUPS web interface (from the Pi or another machine on the same network):

  • Web UI: http://PI-IP:631
    • Administration → Add Printer
    • Choose USB or network printer, select driver/PPD, set name and defaults.

Useful CLI commands:

  • List printers and status:
lpstat -p -d
  • List available devices:
lpinfo -v
  • Add printer via lpadmin (example):
sudo lpadmin -p My_Printer -E -v usb://... -m everywhere
  • Print a test page:
lp -d My_Printer /etc/issue

9) Backup and restore configuration​

Backup the CUPS config and PPD/printer definitions:

sudo tar czf cups-backup-$(date +%F).tar.gz /etc/cups /var/spool/cups /var/cache/cups /var/lib/cups

To restore, unpack to root (test on staging first):

sudo tar xzf cups-backup-YYYY-MM-DD.tar.gz -C /
sudo systemctl restart cups

10) Troubleshooting​

  • CUPS web UI unreachable:

    • Confirm CUPS is running: sudo systemctl status cups
    • Check firewall and that port 631 is reachable.
    • Confirm Listen in cupsd.conf is correct.

  • Printer not detected:

    • Check USB device: lsusb and dmesg | tail -n 50
    • Confirm device node: ls /dev/usb* /dev/tty* (some printers use special backends)

  • Permission denied when printing:

    • Ensure correct ownership/permissions on spool dirs and that user is in lpadmin where needed.

  • Inspect logs:

sudo journalctl -u cups -f
# or
sudo tail -n 200 /var/log/cups/error_log

Set log level in /etc/cups/cupsd.conf (e.g. LogLevel debug) for deep troubleshooting, then revert after.

11) Security considerations​

  • The web admin interface can control printers and server configuration — restrict access to trusted networks and users.
  • Use TLS for remote admin or manage via SSH tunnel.
  • Avoid guest ok = yes and anonymous access on untrusted networks.
  • Keep system and CUPS packages updated.

12) Example quick command summary​

# Update
sudo apt update && sudo apt upgrade -y

# Install CUPS and drivers
sudo apt install -y cups printer-driver-brlaser cups-backend-bjnp

# Add user to lpadmin
sudo usermod -aG lpadmin pi

# Install Samba (optional)
sudo apt install -y samba
sudo systemctl enable --now smbd

# Restart services
sudo systemctl restart cups
sudo systemctl restart smbd

# Check printers
lpstat -p -d
lpinfo -v

CUPS should now be installed and ready. Use the web UI (http://PI-IP:631) to add printers, print test pages and adjust settings. For any production exposure, harden access and use authenticated/secure connections.